Convert rpk ai reference to single-source stubs of docs partials - #161
Conversation
The docs repo is the generation home for rpk ai (asPartial in rpk-overrides.json, generated into reference partials). This replaces the 94 locally generated pages with 101 stubs that include those partials, picking up the rpai 0.2.31 llm-provider/mcp-server renames and the new policy command group. - 21 renamed pages carry page-aliases for their old URLs - rpk ai connection pages dropped (command excluded upstream) - nav rebuilt from the current command tree
✅ Deploy Preview for redpanda-agentic-data-plane ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
|
Before this merges: the new |
Docs reviewThe architecture here is right and the plumbing is almost entirely correct, but there are three blockers before this can land. Critical issues (must fix)1. Alias collision that hard-fails the build.
Fix: delete 2. Every command flag disappears from the reference. The upstream partials contain almost no flag documentation:
Checked against the 0.2.31 plugin: This is a generator defect rather than anything wrong with the stub pattern, but merging is what publishes it. A reference where 3. The Preview label is dropped from the entire Fix: add Suggestions4. 5. Body text is degraded relative to the pages being replaced, and some descriptions are mangled. 6. Empty section gaps. The generator emits three to five blank lines where the Aliases and Flags sections would be, so pages render with odd vertical gaps between Impact on other filesNot in this PR, but affected:
PR description is now stale
One scope note: no local build was run for this review. Finding 1 is verified against Antora's alias-registration behavior and finding 2 against the installed 0.2.31 plugin. A build after fixing finding 1 is the right confirmation step. |
Address review feedback on the stub conversion: - Add :page-preview: true to all 101 stubs. The current pages carry it and moving rpk ai out of Preview is a product decision, not a side effect of single-sourcing. The attribute sits above the include so it survives regeneration of the upstream partials. - Point the CLI index mcp-server link at rpk-ai-mcp-server.adoc directly instead of resolving through the alias. - Update the rpk index intro to the renamed command families (llm-provider, mcp-server, oauth-provider). - Merge main (#159, #160).
rpk-ai-llm-provider.adoc declares rpk-ai-llm.adoc as a page alias, and Antora fails the build when an alias target resolves to a live page. Delete the stub and its nav entry, matching how rpk-ai-mcp.adoc was handled. The matching stale upstream partial is removed in redpanda-data/docs#1849.
micheleRP
left a comment
micheleRP
left a comment
There was a problem hiding this comment.
Reviewed and verified locally — approving. This is the right resolution of the canonical-home question: docs repo stays the generation home (partials), adp-docs is the publication home, same pattern as rpk cloud → cloud-docs.
What I verified (against docs main as of today, post-#1840):
- The stated merge blocker has cleared: docs
mainHEAD is the 26.2 GA merge (redpanda-data/docs#1840). - All 100 stub include targets exist in
modules/reference/partials/rpk-ai/on docsmain, checked file-by-file, and every target carries thesingle-sourcetag. Coverage is complete in both directions (100 partials ↔ 100 stubs, nothing orphaned). - Component/coordinate check:
streaming:reference:partial$...matches docsantora.yml(name: streaming). - 21
:page-aliases:entries cover thellm→llm-providerandmcp→mcp-serverrenames. Aliases live in the stubs, not the partials — consistent with the partials keepingpage-aliasesoutside the tagged region. - Netlify deploy preview is green (it was red pre-#1840, as predicted in the description).
Non-blocking notes:
- The three dropped
rpk ai connectionpages have no redirects. If those URLs show up in analytics or Kapa traffic, add redirects as a follow-up; otherwise fine to leave. - Operational coupling to be aware of: the stubs are static, so a future rpai release that adds a command produces a partial with no stub/nav entry here (command invisible on the ADP site), and one that removes a command deletes the partial and leaves a stub with an unresolved include. I'm raising this on redpanda-data/docs#1834 — the plugin-refresh workflow already computes new/removed commands per run, so it can flag when an adp-docs stub/nav follow-up is needed. Longer term, a stub/nav regenerator in this repo would close the loop.
2 participants
Per the canonical-home discussion: the docs repo generates the
rpk aireference (markedasPartialinrpk-overrides.json, written tomodules/reference/partials/rpk-ai/), so this component's 94 locally generated copies are replaced with 101 single-source stubs — the same pattern as the other shared rpk pages.What you get immediately:
llm-provider/mcp-serverrenames and the complete newpolicygroup (apply/create/delete/diff/get/list/update) are already current in the docs partials.:page-aliases:for the renamed old URLs (rpk-ai-llm-*→rpk-ai-llm-provider-*,rpk-ai-mcp-*→rpk-ai-mcp-server-*).Dropped without successors: the three
rpk ai connectionpages — that command isexclude: truein the upstream overrides (deliberately undocumented). Add redirects if those URLs carry traffic.llm-provider/mcp-server/policypartials these stubs include only reach docsmainwith that PR. Until then this branch's includes don't resolve. Its preview will also stay red until #1840 lands, for the same duplicate-component-version reason as #159/#160.Note: one stale pre-rename partial (
rpk-ai-mcp-create.adoc) still exists in the docs repo and is intentionally not stubbed; we're deleting it upstream as follow-up cleanup.